This is required for docs-ci to work properly.

It is already done in docs.nextstrain.org and ncov:

https://github.com/nextstrain/docs.nextstrain.org/blob/5b82daa7d6f9f784e93bdef967af101f91fd2c75/Makefile#L4-L7
https://github.com/nextstrain/ncov/blob/822a77ba070d1d37483d45c22a00b5f83d16e974/docs/Makefile#L4-L7

This uses a reusable workflow in the nextstrain/.github repo.

rST is our standard doc format; Markdown is the legacy format.

Initial conversion performed with:

    pandoc -f markdown-smart -t rst-smart docs/faq/metadata.md > docs/faq/metadata.rst

and then I hand reviewed and made additional edits.

This fixes a broken link to https://docs.nextstrain.org/en/latest/guides/bioinformatics/lat_longs.html.

The page was renamed in nextstrain/docs.nextstrain.org@a3b3856.

This was causing a warning when building the docs:

    Tests
    -----
    None:8: CRITICAL: Unexpected section title.

Removing since docstrings in other files do not have this heading.

In CLI pages with multiple headings.

Replace the literal blocks (introduced by the :: markers) with
code-block directives for nice syntax highlighting.

Fixes this warning:

    augur/io/__init__.py:docstring of augur.io:1: WARNING: duplicate object description of augur.io, other instance in api/developer/augur.io, use :noindex: for one of them

While :noindex: for Sphinx in general disables cross-referencing¹ and it
is briefly mentioned in the "Options and advanced usage" section of
automodule², there aren't any references anyways (as demonstrated by a
lack of related warnings/errors).

However, it's still unclear to me exactly why this shows on augur.io
only. I assume it has something to do with the re-exporting of public
API functions, which is currently specifi to augur.io.

¹ https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#basic-markup
² https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directives

The section headings resulted in warnings:

    None:8: CRITICAL: Unexpected section title.

    Comparison methods
    ==================
    None:36: CRITICAL: Unexpected section title.

    Distance maps
    =============

They rendered fine in the Development API page¹ but did not render on
the CLI page².

This seems like a bug with sphinx-argparse³. For now, use bold text to
avoid the warnings and allow the text to render on the CLI page.

¹ https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.distance.html
² https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/distance.html
³ sphinx-doc/sphinx-argparse#31

This makes local builds show the same warnings in CI without erroring.

Without this prefix, a warning appears:

    WARNING: py:attr reference target not found: ValidationMode.SKIP

The majority of the codebase uses numpydoc for type annotations.
However, there are some usages of the newer PEP 484 type hints.

For example, augur.dates.get_numerical_dates has `metadata:pd.DataFrame`
in the function signature.

Without sphinx-autodoc-typehints, this caused a warning:

    augur/augur/dates.py:docstring of augur.dates.get_numerical_dates:1: WARNING: py:class reference target not found: pandas.core.frame.DataFrame

This commit fixes that warning.

This enables proper reference resolution during the docs build, and
provides useful links on the generated doc pages.

Without these pages, there would be warnings such as:

    WARNING: py:class reference target not found: AugurError
    WARNING: py:class reference target not found: DataErrorMethod

It's a good idea to have these doc pages regardless.

np.isscalar will return true for a float, but that is not valid input
for np.linspace(num).

Instead, allow native or numpy integers.

Otherwise the doctest gets parsed as numpydoc.

Better than the previous commit since this section is made for doctest examples¹.

¹ https://numpydoc.readthedocs.io/en/v1.5.0/format.html#examples

The bracket notation is suggested by PyCharm¹ but is not standard
numpydoc.

¹ https://www.jetbrains.com/help/pycharm/type-syntax-for-docstrings.html

"label" is not a valid type; it should be "str".

These resulted in nitpick "reference target not found" warnings.

Other register_parser functions don't have a docstring, and this one is
out of date.

These were causing nitpick warnings:

    WARNING: py:class reference target not found: TYPE

Bio.Phylo is the module, not the tree class.

This could instead be something more specific like
Bio.Phylo.Newick.Tree, but I opted for the more generic type.

`Phylo.Node` is not a valid class. I believe the intention is
`Bio.Phylo.BaseTree.Clade`, since that is the type of
`Bio.Phylo.BaseTree.Tree.root`

This class lives at pandas.io.parsers.TextFileReader, however, there are
no public docs for it and it isn't linked on pandas doc pages either¹.

Use single backticks to disable linking while denoting that it is a class².

¹ https://pandas.pydata.org/pandas-docs/version/1.4/reference/api/pandas.read_csv.html
² https://numpydoc.readthedocs.io/en/latest/format.html#common-rest-concepts